Inside Macintosh: QuickDraw GX Graphics /

Chapter 6 - Picture Shapes / Picture Shapes Reference

Functions / Editing Picture Parts

GXSetPictureParts

You can use the GXSetPictureParts function to add, remove, or replace a range of picture items in a picture shape's geometry.

void GXSetPictureParts(gxShape target, long index, long oldCount,
                       long newCount, const gxShape shapes[],
                       const gxStyle styles[], 
                       const gxInk inks[], 
                       const gxTransform transforms[]);

target

A reference to the picture shape whose picture item list you want to alter.

index

The number of the first picture item you want to replace.

oldCount

The total number of picture items you want to replace. A value of 0 indicates that you want to insert new picture items before the existing picture item indicated by the index parameter, rather than replace items. You may supply the gxSelectToEnd constant (-1) to indicate that you want to replace all picture items (starting with the picture item indicated by the index parameter.)

newCount

The total number of new picture items to insert in the picture. A value of 0 specifies that you do not want to insert new items into the picture; instead, the existing items you specified with the index and oldCount parameters are removed.

shapes

An array of references to the shapes to include as the new picture items in the new picture geometry.

styles

An array of references to the style objects you want to use as overriding styles in the new picture geometry. You may provide gxSetToNil for this parameter if you do not want any overriding styles.

inks

An array of references to the ink objects you want to use as overriding inks in the new picture geometry. You may provide gxSetToNil for this parameter if you do not want any overriding inks.

transforms

An array of references to the transform objects you want to use as overriding transforms in the new picture geometry. You may provide gxSetToNil for this parameter if you do not want any overriding transforms.

DESCRIPTION

The GXSetPictureParts function allows you to insert new picture items in a picture, to remove picture items from a picture, or to replace picture items with new picture items. In any of these three cases, the target parameter specifies the picture to be modified, the oldCount parameter specifies the number of items to remove, the newCount parameter specifies the number of items to add, and the shapes, styles, inks, and transforms parameters specify the information for the new picture items.

• To insert picture items, set the oldCount parameter to 0. Use the index parameters to specify where to add the new picture items. (This function inserts the new picture items before the existing item you specify with the index parameter. For example, if you specify 1 for this parameter, the new picture items are inserted before the first item of the existing picture item list.)
• To remove picture items, set the newCount parameter ot 0 and the shapes, styles, inks, and transforms parameters to nil. Use the index and oldCount parameters to specify which picture items to remove.
• To replace picture items, use the index and oldCount parameters to specify the existing picture items to remove and use the newCount, shapes, styles, inks, and transforms parameters to specify the new picture items to insert in their place.

To maintain correct owner counts, this function clones the inserted shapes, styles, inks and transforms, and disposes of any replaced shapes, styles, inks, and transforms.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
parameter_out_of_range	(debugging version)
index_is_less_than_one	(debugging version)
count_is_less_than_one	(debugging version)
cannot_set_item_shapes_to_nil	(debugging version)
cannot_use_original_item_shapes_when_growing_picture
	(debugging version)
Warnings
index_out_of_range
count_out_of_range
picture_expected	(debugging version)
shape_access_not_allowed	(debugging version)
picture_cannot_contain_itself	(debugging version)
cannot_dispose_locked_tag	(debugging version)
cannot_dispose_default_shape	(debugging version)
cannot_dispose_default_style	(debugging version)
cannot_dispose_default_ink	(debugging version)
cannot_dispose_default_transform	(debugging version)
cannot_dispose_default_colorProfile	(debugging version)

SEE ALSO

For information about picture items and their overriding styles, inks, and transforms, see "About Picture Shapes" beginning on page 6-3.

For examples using this function, see "Removing and Replacing Items in a Picture" beginning on page 6-35.

To extract information from a subset of the items contained in a picture shape's geometry, use the GXGetPictureParts function, which is described on page 6-63.

To replace every item in a picture geometry, use the GXSetPicture function, which is described on page 6-61.

For information about disposing of shapes, see the chapter "Shape Objects" in Inside Macintosh: QuickDraw GX Objects.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help